Skip to content

Conversation

paulomach
Copy link

@paulomach paulomach commented Aug 22, 2025

Onboard linting rules from server.

@paulomach paulomach added the not bug or enhancement PR is not 'bug' or 'enhancement'. For release notes label Aug 22, 2025
"E501", # Line too long (because using black creates errors with this)
"N818", # Exception name should be named with an Error suffix
"W505", # Doc line too long (so that strings in comments aren't split across lines)
"S101",
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

S101 is the only differing config between this and others (mysql-server, pg*), and it's related to the usage of assert's in the code.
@carlcsaposs-canonical I would prefer removing those, but I've added the ignore to get your position.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

charms aren't run with -O, so asserts should always run

I think asserts are valuable for

  • documenting assumptions that should never get raised
  • they are much shorter than raising exceptions

I think adding s101 will result in less assumptions getting documented (an assert is much cheaper than if: raise)

yes we should raise exceptions (and not assert) for expected errors, but I don't think we should get rid of assert for documenting assumptions

ctrl-f "assert" in https://github.com/canonical/charm-refresh/blob/main/charm_refresh/_main.py for some examples of things I wouldn't bother writing code to raise an exception for but is worth writing an assert to document the assumption

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My 2 cents is that asserts in production code is weird, due:

they are much shorter than raising exceptions

Short code is not something to pursue and I disregard it as a good argument. We should pursue being explicit instead.

documenting assumptions that should never get raised

Being explicit does a better job and, assert's will result in lost of granularity for error catching as all errors will be AssertionError

Copy link
Contributor

@carlcsaposs-canonical carlcsaposs-canonical Aug 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

assert's will result in lost of granularity for error catching

imo we should never be catching asserts—if we're catching, a proper exception should be raised

Short code is not something to pursue

I think it's significantly more readable and, practically speaking, the alternative would be to not document assumptions at all instead of raising exceptions
for a concrete example, I think the refresh code linked above would be a lot harder to follow if the asserts were replaced with if: raise—assert makes it clear that it's validating an assumption instead of an expected error case and it keeps the "business logic" clear/front and center

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👋🏻 My 2 cents about this topic is that we should avoid using assertions.

I agree that the assertions are shorten than properly defined + raised exceptions, but I think we should strive for the latter and do not take shortcuts. Both the name and doc-string of the substitute exceptions will replace the documentation value of the assertions, possibly even surpassing it.

In short: I am in favor of applying S101.

Copy link

@taurus-forever taurus-forever left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice!

"B",
"CPY001",
"RUF",
"S",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"S",

looks like this causes a lot of false positives, don't think it's worth the hassle
e.g. https://github.com/search?q=repo%3Acanonical%2Fmysql-operator%20s105&type=code

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👋🏻 My 2 cents about this topic is that the S linting rule should stay, as there are a bunch of security related misconfigurations it could detect. I recognize S105 is annoying, but I think the benefits outweigh the drawbacks.

"CPY001",
"RUF",
"S",
"SIM",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"SIM",

imo, many of these rules decrease readability of the code

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👋🏻 My 2 cents about this topic is that the SIM linting rule should not stay, as some of the rules enforce syntax that we may not want to apply, either for readability purposes, or because we want to sneak a comment right in the middle of two statements.

It it up to you if you want to fine-tune the rules and select only those that are overwhelmingly benign (i.e. double-negation, expr-with-true-false...)

"E501", # Line too long (because using black creates errors with this)
"N818", # Exception name should be named with an Error suffix
"W505", # Doc line too long (so that strings in comments aren't split across lines)
"S101",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"S101",
"S101",
"B011",
"B903",
"B904", # Exception chaining happens automatically if `from` omitted
"RUF005",
"RUF010",

b011 for same reason as s101
b903 class with only __init__ shouldn't always be a dataclass
b904 unnecessarily verbose, default behavior of exception chaining (when from omitted) is almost always desired
ruf005 imo premature optimization; sometimes less readable
ruf010 imo decreases readability

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👋🏻 My 2 cents here highly varies from rule to rule:

  • B011 - Unnecessary if S101 gets apply, which I am in favour of.
  • B903 - No preference.
  • B904 - No preference, although if exception names are fine-grained enough, I will say unnecessay.
  • RUF005 - I like it, and find it more readable than concatenating using +.
  • RUF010 - No preference.

"W505", # Doc line too long (so that strings in comments aren't split across lines)
"S101",
]

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
[tool.ruff.lint.ruff]
parenthesize-tuple-in-subscript = true

change behavior of ruf031 to be more readable

"E501", # Line too long (because using black creates errors with this)
"N818", # Exception name should be named with an Error suffix
"W505", # Doc line too long (so that strings in comments aren't split across lines)
"S101",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

charms aren't run with -O, so asserts should always run

I think asserts are valuable for

  • documenting assumptions that should never get raised
  • they are much shorter than raising exceptions

I think adding s101 will result in less assumptions getting documented (an assert is much cheaper than if: raise)

yes we should raise exceptions (and not assert) for expected errors, but I don't think we should get rid of assert for documenting assumptions

ctrl-f "assert" in https://github.com/canonical/charm-refresh/blob/main/charm_refresh/_main.py for some examples of things I wouldn't bother writing code to raise an exception for but is worth writing an assert to document the assumption

@paulomach
Copy link
Author

@carlcsaposs-canonical , we are disputing s101
The other's should stay as they enforce us some common practices and bigger standardization on the codebase

@carlcsaposs-canonical
Copy link
Contributor

The other's should stay as they enforce us some common practices and bigger standardization on the codebase

do we not have input on the code style of the codebases we maintain?

for more concrete examples:

I think it's important to find a balance so that linting is useful/helpful instead of pedantic/annoying/more of a hassle than it adds
Especially for rules with frequent false positives, I think we should be mindful of rules that we add to ensure that they add more value than they cost

Copy link

@sinclert-canonical sinclert-canonical left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure this PR will ever get merged. If it does, I left my preferences to most of the discussed rules in a series of comments, each within their specific thread:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Libraries: Out of sync not bug or enhancement PR is not 'bug' or 'enhancement'. For release notes
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants